<!-- BeginDsi "dsi/head.html" -->
<!DOCTYPE html>
<html lang="en">
<head>
    <title>Embedthis GoAhead 3.1.1 Documentation</title>
    <meta name="keywords" content="embedded web server, web server software, embedded HTTP, application web server, 
        embedded server, small web server, HTTP server, library web server, library HTTP, HTTP library" />
    <meta name="description" content="Embedthis Sofware provides commercial and open source embedded web servers for 
        devices and applications." />
	<meta name="robots" content="index,follow" />
	<link href="../../../doc.css" rel="stylesheet" type="text/css" />
	<link href="../../../print.css" rel="stylesheet" type="text/css" media="print"/>
    <!--[if IE]>
    <link href="../../../iehacks.css" rel="stylesheet" type="text/css" />
    <![endif]-->
    <link href="http://www.google.com/cse/style/look/default.css" type="text/css" rel="stylesheet" />
    <script type="text/javascript">
        var _gaq = _gaq || [];
        _gaq.push(['_setAccount', 'UA-179169-5']);
        _gaq.push(['_trackPageview']);
        (function() {
            var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
            ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
            var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
        })();
    </script>
</head>

<body>
    <div class="top">
        <a class="logo" href="http://embedthis.com/products/goahead/">&nbsp;</a>
        <div class="topRight">
            <div class="search">
                <div id="cse-search-form"></div>
                <div class="version">Embedthis GoAhead 3.1.1</div>
            </div>
        </div>
        <div class="crumbs">
            <a href="../../../index.html">Home</a>
<!-- EndDsi -->
             &gt;<a href="index.html">Source Code</a> &gt; <b>Porting GoAhead</b>
        </div>
    </div>
    <div class="content">
        <div class="contentRight">
            <div class="linkSection">
                <h1>Quick Nav</h1>
                <ul>
                    <li><a href="#newOs">Porting to a new O/S</a></li>
                    <li><a href="#workingWithTheTeam">Working with the Team</a></li>
                </ul>
<!-- BeginDsi "dsi/sourceSeeAlso.html" -->
            <h1>See Also</h1>
            <ul class="nav">
                <li><a href="../../../guide/goahead/source/index.html">Working with Source</a></li>
                <li><a href="../../../guide/goahead/source/building.html">Building From Source</a></li>
                <li><a href="../../../guide/goahead/source/porting.html">Porting Guide</a></li>
                <li><a href="../../../ref/goahead/index.html">Programmers Reference</a></li>
                <li><a href="../../../guide/goahead/programmers/embedding.html">Embedding GoAhead</a></li>
                <li><a href="../../../guide/goahead/programmers/handlers.html">GoAhead Handlers</a></li>
                <li><a href="../../../guide/goahead/programmers/migrating.html">Migrating to GoAhead 3</a></li>
                <li><a href="../../../guide/goahead/users/index.html">Users Guide</a></li>
                <li><a href="../../../product/changeLog.html">Change Log</a></li>
            </ul>
<!-- EndDsi -->
            </div>
        </div>
        <div class="contentLeft">
            <h1>Porting GoAhead</h1>
            <p>Porting any software is not for the novice. It requires considerable skill to read another person's code
            and adapt it to a new environment. These instructions are intended for experienced developers who want to
            port GoAhead to a new operating system or processor architecture.</p>
            <p>GoAhead has been written to maximize the ease of porting to a new environment. The O/S and
            processor-dependent code have been contained while the bulk of the code is cross-platform. Most of this
            dependent code is in the <b>runtime.c</b> source file.</p>
            <p><b>NOTE:</b> When attempting a port, you should get the latest copy of the development source 
            rather than using the download source package. You can get the latest development source by checking out a
            copy from the <a href="https://github.com/embedthis/goahead">repository</a>.</p>
            <p><b>NOTE:</b> Please read <a href="building.html">Building from Source</a> before your read this
            document. It provides valuable background about building from source.</p>
            
            <a id="newOs"></a>
            <h2>Steps in Porting to a new Operating System</h2>
            <ol>
                <li><h3>Pick a Name for the O/S</h3>
                    <p>If you are porting to a new operating system, you need to pick a symbolic name that will
                    be used in conditional compilation, Makefiles, bit files, and operating system specific 
                    directories. Some existing O/S names are: "linux", "windows", "freebsd", and "macosx".</p>
                    <p>These names are used as upper-case pre-processor defines and in some cases as lower-case
                        directory names.</p>
                </li>
                <li><h3>Select the base O/S to Copy</h3>
                    <p>The easiest way to port to a new O/S is to find the closest existing supported O/S that the
                    GoAhead software already supports and use it as a base to modify. For example, if you are porting to
                    QNX, you may want to use the Linux port as a base.</p></li>
                <li><h3>Create the output products directory</h3>
                    <p>You need to create a directory for the build products: objects, binaries etc. This should 
                    be named OS-ARCH-PROFILE. For example: qnx-x86-debug. Under this directory create the inc, bin and 
                    obj directories.</p>
                    <pre>
mkdir -p qnx-x86-debug/bin qnx-x86-debug/obj qnx-x86-debug/inc
</pre>
                <li><h3>Create the Makefile</h3>
                <p>Create the Makefile by copying the makefile for the similar O/S. i.e. in our example, 
                Copy the projects/goahead-linux.mk Makefile to projects/goahead-qnx.mk. Then edit the
                appropriate compiler and linker switches. Edit the top level Makefile if required to chain to this
                    new Makefile.</p>
                    <pre>
cp projects/goahead-linux.mk projects/goahead-qnx.mk
vi projects/goahead-qnx.mk
</pre>
                </li>
                <li><h3>Tailor the cross-platform O/S header.</h3>
                    <p>To insulate most of the GoAhead source code from the differences of various operating systems,
                    the <em>src/bitos.h</em> header file wraps all the required O/S headers and publishes a
                    consistent set of types and prototypes. None of the source files include normal O/S headers like
                    &lt;string.h&gt;. While this does slow the build by including more headers than are required
                    &mdash; it is barely noticeable on modern CPUs.</p>
                    <p>When porting the bitos.h, start by copying the sections in bitos.h that pertain to your base 
                    copied O/S.
                    These will be protected by "#if BASEOS" defines. In the example of QNX, we would look for, and
                    copy, any sections with "#if LINUX" and create "#if QNX" sections.</p>
                    <p><b>DO NOT</b> introduce conditional code in other O/S sections. It is better to copy the entire
                    contents from the base O/S and modify. It is better to isolate the code for each O/S.</p>
                </li>
                <li><h3>Test the Headers with a Hello World Program.</h3>
                    <p>Don't use the make system yet. Just create an empty C hello world program and include "bitos.h".
                    Compile it and shake out the issues. </p>
                </li>
                <li>
                    <h3>Port the per O/S runtime source code</h3>
                    <p>Now is the time for the real work. You will need to modify the runtime.c file to support your
                    new platform. Search for conditionals for the BASEOS you chose and copy and modify these sections.</p>
                </li>
                <li>
                    <h3>Test the runtime</h3>
                    <p>To start out, test compile just the runtime.</p>
                    <pre>
make NEWOS-ARCH-debug/obj/runtime.o
</pre>
                    <p>At this stage of the porting effort, the <b>make</b> command will undoubtedly provoke a stream
                    of errors. Use this to work out the bugs in bitos.h and runtime.c for your O/S.</p>
                </li>
                <li>
                    <h3>Compile the Rest</h3>
                    <p>After the runtime, it is more downhill. The rest of the code should compile and build more easily. 
                    It is quite cross-platform.</p>
                    <pre>
make
</pre>
                </li>
                <li>
                    <h3>Test GoAhead</h3>
                    <pre>
cd test
goahead-test -v
</pre>
                </li>
            </ol>
            
            <a id="workingWithTheTeam"></a>
            <h2 class="section">Working with the GoAhead Development Team</h2>
            <p>Once you have a basic port running, you should send it back for the team to look over. They can provide
            advice and suggestions. At the first opportunity, your changes may be merged back into the development tree
            so others can benefit from your work.</p>
            <p>Good luck and have fun. Please give feedback to the development team at <a href=
            "mailto:dev@embedthis.com">dev@embedthis.com</a>.</p>
        </div>
    </div>
<!-- BeginDsi "dsi/bottom.html" -->
	<div class="bottom">
		<p class="footnote"> 
            <a href="../../../product/copyright.html" >&copy; Embedthis Software LLC, 2003-2013.
            All rights reserved. Embedthis and Embedthis GoAhead are trademarks of Embedthis Software LLC.</a>
		</p>
	</div>
    <script src="http://www.google.com/jsapi" type="text/javascript"></script>
    <script type="text/javascript"> 
      google.load('search', '1', {language : 'en'});
      google.setOnLoadCallback(function() {
        var customSearchControl = new google.search.CustomSearchControl(
          '000262706376373952077:1hs0lhenihk');
        customSearchControl.setResultSetSize(google.search.Search.FILTERED_CSE_RESULTSET);
        var options = new google.search.DrawOptions();
        options.enableSearchboxOnly("http://embedthis.com/search.html");
        customSearchControl.draw('cse-search-form', options);
      }, true);
    </script>
</body>
</html>
